home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1998 May / EnigmA AMIGA RUN 27 (1998)(G.R. Edizioni)(IT)[!][issue 1998-05].iso / recent1 / gifani.lha / gifanim_datatype / gifanim.datatype.doc < prev    next >
Text File  |  1998-04-13  |  30KB  |  743 lines
  1. TABLE OF CONTENTS
  2.  
  3. gifanim.datatype/--datasheed--
  4. gifanim.datatype/--input_format--
  5. gifanim.datatype/ADTM_LOADFRAME
  6. gifanim.datatype/ADTM_UNLOADFRAME
  7. gifanim.datatype/DTM_WRITE
  8. gifanim.datatype/MAIN
  9. gifanim.datatype/OM_DISPOSE
  10. gifanim.datatype/OM_NEW
  11. gifanim.datatype/preferences
  12. gifanim.datatype/--datasheed--                 gifanim.datatype/--datasheed--
  13.  
  14.    NAME
  15.        gifanim.datatype -- data type for GIF Animations
  16.  
  17.    SUPERCLASS
  18.        animation.datatype
  19.  
  20.    DESCRIPTION
  21.        The anim datatype, a sub-class of the animation.datatype, is used to
  22.        load, play and encode (save) GIF animations.
  23.        It supports GIF 87a and GIF 89a compressed animations.
  24.        Using the prefs-file, any sound can be attached to the animation.
  25.  
  26.    METHODS
  27.        OM_NEW -- Create a new animation object from a description file. The
  28.            source may only be a file. Or an empty object can be created for 
  29.            encoding (which must be filled by the application before 
  30.            encoding).
  31.  
  32.        OM_DISPOSE -- Dispose instance and contents (frames, colormaps, sounds
  33.            etc.), then pass msg to superclass
  34.  
  35.        OM_UPDATE -- Perform an ICM_CHECKLOOP check, and if succesfull, the
  36.            method will be executed like OM_SET downstairs.
  37.  
  38.        OM_SET -- Pass msg to superclass and call GM_RENDER if retval from
  39.            superclass was != 0UL.
  40.  
  41.        DTM_WRITE -- Save object's contents in local (GIF Animation) or
  42.            superclass (IFF ILBM) format.
  43.  
  44.        ADTM_LOADFRAME -- Fill in struct adtFrame with requested information
  45.            from internal FrameNode list like bitmap, colormap and sample. If
  46.            the bitmap information is not loaded yet, it will be loaded from
  47.            disk.
  48.  
  49.        ADTM_UNLOADFRAME -- Free resources obtained by ADTM_UNLOADFRAME.
  50.  
  51.        All other methods are passed unchanged to superclass.
  52.  
  53.    ATTRIBUTES
  54.        Following attributes are set by the object and are READ-ONLY for
  55.        applications:
  56.        DTA_ObjName             - file name
  57.        DTA_ObjAnnotation       - set by extension blocks (gif 89a comment
  58.                                  extention)
  59.        DTA_TotalHoriz          - same as ADTA_Width
  60.        DTA_TotalVert           - same as ADTA_Height
  61.        ADTA_Width              - set by GIF screen
  62.        ADTA_Height             - set by GIF screen
  63.        ADTA_Depth              - set by GIF screen
  64.        ADTA_Frames             - number of frames in animation
  65.        ADTA_FramesPerSecond    - fixed to 100 fps
  66.        ADTA_ModeID             - mode id flags
  67.        ADTA_KeyFrame           - Key frame of animation
  68.  
  69.        The following attributes are only set if a sample is attached using 
  70.        the prefs-file:
  71.        ADTA_Sample             - only set to notify the anmation.datatype
  72.                                  instance that the object has sound data
  73.        ADTA_SampleLength       - size of sample data played within one 
  74.                                  timestamp
  75.        ADTA_Period             - sample period
  76.        ADTA_Volume             - volume as set by the prefs-file
  77.  
  78.    BUGS
  79.        * The whole code looks like a big hack; sorry, but this datatype was
  80.          put together within 2 hours...
  81.          ...V1.2 only fixes some bugs and adds a few features.
  82.          ...V1.3 fixed some things, adds some legal stuff and CyberGFX
  83.             support
  84.  
  85.        - Does not support transparency yet (the encoder supports 
  86.          transparency througth a prefs-option).
  87.  
  88.        - Very slow playback.
  89.          Reasons:
  90.          - Multiple memory allocations, Seek's and Read's in one
  91.            ADTM_LOADFRAME
  92.          - Unbufferd loading
  93.          - C2P conversion (fast, but not the fastest possible)
  94.          - crap design
  95.          - Slow gif decoder. Rewriting the beast in ASM maybe speed up
  96.            things, but I don't know much about m68k assember.
  97.            Anybody out there who wants to do the job ?
  98.          ....
  99.  
  100.          To get rid of this problem, the LOADALL switch is set for now.
  101.          On >= mc68040/40MHz, the LOADALL switch in unneccesary, use
  102.          NOLOADALL in this case...
  103.  
  104.        - Some anims get a trashed background, maybe due a bug in the GIF89a
  105.          frame disposal support code.
  106.          Any hint/example animation ?
  107.  
  108.        - This datatype was written for animation.datatype V41. Using this
  109.          datatype with animation.datatype V40.6 does not work !
  110.          Not a bug, but...
  111.  
  112.        - In large videos, the frames at the end will be played slower than
  113.          those at the beginning of the file. This is the result of the
  114.          sequential search internally used (only serious with more than 25000
  115.          frames (mc6030/50mhz)).
  116.          May or may not be fixed.
  117.  
  118.        - CyberGFX support is still under development. It seems that it works
  119.          good, but...
  120.  
  121.        - CyberGFX C2C conversion (LUT8 -> RGB16/24) uses a very crap method
  122.          througth WriteRGBPixel...
  123.  
  124.    TODO
  125.        - Fixing the bugs above.
  126.  
  127.        - Write the "--input_format--"-Autodoc section.
  128.  
  129.    HISTORY
  130.        V1.1
  131.          Released to the Waldspecht-BBS for testing.
  132.  
  133.        V1.2
  134.          - Found and fixed the longstanding bug that animation.datatype
  135.            V40.7 didn't free some frames. Reason is that ADTM_LOADFRAME
  136.            may be used like "realloc". Now alf_UserData is checked;
  137.            any given frame will be freed (ADTM_UNLOADFRAME).
  138.            Fixed.
  139.  
  140.          - Minor houskeeping changes; removed some unneccesary code.
  141.  
  142.          - Now uses buffered reading (FRead instead of Read and SetVBuf).
  143.            Maybe this speeds up loading a little bit.
  144.  
  145.          - Fixed the bug in NOLOADALL loading mode (dynamic loading of
  146.            frames from disk) that some "disposal" modes (previous image)
  147.            didn't work properly under some conditions.
  148.            Fixed.
  149.  
  150.          - Fixed the bug that animations with a static background were
  151.            not correctly handled in LOADALL mode (I simply forgot
  152.            to write the code...).
  153.            Thanks to Francis Labrie (fb691875@er.uquam.ca) for reporting
  154.            the bug.
  155.            Fixed.
  156.  
  157.          - Fixed the bug that ADTM_LOADFRAME returns evertimes
  158.            ERROR_NO_FREE_STORE on failure instead of returning the real
  159.            cause.
  160.            Also fixed the error handling code in ADTM_LOADFRAME.
  161.            Fixed.
  162.  
  163.          - Implemented a delta mode for WPA8. If possible (e.g. if the
  164.            current frame uses the previous one as it's background), only
  165.            the changed areas are processed by the C2P code.
  166.  
  167.          - Now supports the GIF comment extension. The character set is
  168.            converted automatically, chars > 128 are replaced by '_'
  169.            except the german 'ä', 'ö', 'ü', 'Ä', 'Ö', 'Ü' and 'ß'.
  170.            Multiple comment chunks are merged together.
  171.            The comment will be stored in DTA_ObjAnnotation.
  172.  
  173.          - Cut some unneccesary VERBOSE output.
  174.  
  175.        V1.3
  176.          | Internal testing release to search for the mysterious memory loss
  177.          | in conjunction with the 24BITCHUNKY option.
  178.  
  179.          - Added the notice that UniSys holds the LZW patents in the USA.
  180.  
  181.          - Removed BestModeIDA, because animation.datatype does the same
  182.            thing.
  183.  
  184.          - Small code cleanup.
  185.            Removed some of the debugging code and removed some parts of
  186.            dead code.
  187.  
  188.          - Fixed the "maximum timestamp" (ADTA_Frames) calculation.
  189.            the old way was very crap...
  190.            Fixed.
  191.  
  192.          - Added some padding bytes in the decoder (instance data) part.
  193.            Now the data are aligned, which should speed up the decoding.
  194.  
  195.          - Fixed possible problems when a GIF "Comment Extension" text is
  196.            not '\0'-terminated. Now the load buffer is zero'ed for each new
  197.            cycle.
  198.            Fixed.
  199.  
  200.          - Added some VERBOSE about the "Plain Text Extension". The contents
  201.            are now shown in the verbose output.
  202.  
  203.          - Fixed the bug that in the case that the first frame has no bitmap
  204.            a bitmap with 0,0,0 dimensions would be allocated.
  205.            (Did not occur, but...)
  206.            Fixed.
  207.  
  208.          - Implemented a prefetch buffer for dynamic load mode (e.g.
  209.            NOLOADALL); now all data needed for the frame are loaded with one
  210.            Read statement, all following accesses are redirected to the
  211.            filled buffer.
  212.            Switched from FRead to Read again because we're now loading
  213.            larger blocks.
  214.  
  215.          - Fixed the width padding problem, which caused an ugly border
  216.            filled with rubbish in some anims.
  217.            Fixed.
  218.  
  219.          - Now supports different disposal modes in one animation (each
  220.            frame can have it's own disposal mode).
  221.  
  222.          - Now supports different transarent colors in one animation (each
  223.            frame can have it's own transparent color).
  224.  
  225.          - Removed all references to ADTA_BitMapHeader. It's not required
  226.            for this format.
  227.  
  228.          - Now saves the transparent color values from the previous colormap.
  229.  
  230.          - Fixed the bug that the datatypes creates everytimes a
  231.            palette-per-frame instead of creating them only if neccesary.
  232.            Fixed.
  233.  
  234.          - Now sets the GIF Screen background color to 0 if there is no
  235.            global colormap.
  236.  
  237.          - Added CyberGFX-Support. Upon request, the datatype tries to create
  238.            a 24-bit chunky bitmap if the 24BITCHUNKY prefs switch is set.
  239.            WARNING: Does only work with animation.datatype V41 or higher
  240.            (<= V41.2 had a small bug which has been fixed in V41.3).
  241.  
  242.          - Added CyberGFX bug workaround when BestCModeIDA fails when the
  243.            dimensions given are too small (e.g. 32 * 50 returns INVALID_ID).
  244.            Then 640 * 480 are set.
  245.            Not very nice.
  246.  
  247.          - Added GIF Picture descriptor to replace any version with a wrong
  248.            mask.
  249.  
  250.        V1.4
  251.          - Very much thanks to Frank Mariak (fmariak@chaosengine.ping.de)
  252.            for finding the silly "too big palette"-bug in conjunction
  253.            with the new chunkypixel output.
  254.  
  255.        V1.5
  256.          - Major code cleanup. BOOPSI class structures have been moved
  257.            to classdata.h, class independed functions have been moved
  258.            into misc.c, class preferences to prefs.c
  259.  
  260.          - Replaced the custom stackswapping code with my "standard"
  261.            module "stackswap.c".
  262.  
  263.          - OM_DISPOSE now preserves Result2 (IoErr()).
  264.  
  265.          - Fixed the longstandig bug in ScanFrames that if an OS function
  266.            failed, and IoErr results 0, havoc broke out.
  267.            Fixed.
  268.  
  269.          - ADTA_SampleLength calculations were wrong. The value was got
  270.            from the first frame. Now the value is set correctly to
  271.            alf_SampleLength / (alf_Duration + 1)
  272.            Fixed.
  273.  
  274.          - If a ADTM_LOADFRAME method gets a message from a previous
  275.            ADTM_LOADFRAME call, the contents are freed now after
  276.            the requested data have been loaded. This avoids the
  277.            pathological case that if the same frame should be freed and
  278.            returned the frame IS freed and then re-loaded.
  279.            Now the free of the given frame is done after the loading
  280.            of the requested frame which avoids this inefficienty.
  281.            Fixed.
  282.  
  283.          - Switched truecolor output down to 16 bit (565-bits-per-gun)
  284.            to save some mem...
  285.  
  286.          - Added 16BITCHUNKY, NO16BITCHUNKY, TRUECOLOR and NOTRUECOLOR
  287.            options.
  288.  
  289.          - Fixed ModeID handling. The previous behaviour was that
  290.            a 0 mode id causes the datatype to select it's own mode id.
  291.            But 0 means LORES. Now the default is -1 (which means
  292.            INVALID_ID), which causes the datatype to do it's own
  293.            calculations.
  294.            Fixed.
  295.  
  296.        V2.1
  297.          - Implemeted the GIF animation encoder part.
  298.            The encoder writes GIF89a animation streams out.
  299.  
  300.          - Fixed a mask bug in the suppied "GIF" descriptor;
  301.            a byte after the "GIF" signature was set to match,
  302.            Fixed.
  303.  
  304.          - gifanim.datatype now requires at least animation.datatype V41
  305.            as base class.
  306.            (mainly to get rid of the V40 workround code which tried to
  307.            get class working with animation.datatype V40).
  308.  
  309.          - Updated and cleaned-up the autodoc a little bit.
  310.  
  311.        V2.2
  312.          - Minor code cleanup
  313.  
  314.          - Removed REPEAT and NOREPEAT options/feature because this
  315.            hack-like "feature" seems to be incompatible to GMultiView's
  316.            repeat option.
  317.            Problem fixed.
  318.  
  319.          - Added encoder prefs options to set GIF interlace mode, transparent
  320.            and background pens.
  321.            See "gifanim.datatype.doc" section "preferences" for details.
  322.            Currently untested...
  323.  
  324.          - Major speedup in the encoder part (~ three times faster).
  325.            a) The encoder now writes any incoming bitmap in an chunkypixel
  326.               array and operates on it instead of doing ReadPixel for
  327.               each pixel.
  328.            b) Minor other changes in the encoder section...
  329.  
  330.          - The decoder now treats 0x00-chars in the chunk id position as 
  331.            padding bytes and does not prompt any sytax error any more.
  332.            Now the "slidbar.gif" created by "GifBuilder 0.2" works...
  333.  
  334.          - Introduced the option STRICTSYNTAX which prints additionally 
  335.            syntax errors (like the 0x00 padding bytes above...).
  336.  
  337.          - Added Installation script "Install DataType". 
  338.            It would be very nice if someone has the time to write a
  339.            1:1 CBM Installer version of it...
  340.  
  341.  
  342.    NOTES
  343.        This datatype first scans the whole animation to get index
  344.        information (if the LOADALL switch was set in the prefs-file,
  345.        the entire animation will be loaded), colormaps will be loaded
  346.        immediately.
  347.  
  348.    SEE ALSO
  349.        animation.datatype,
  350.        anim.datatype,
  351.        mpegsystem.datatype, mpegvideo.datatype,
  352.        picmovie.datatype,
  353.        cdxl.datatype, avi.datatype, quicktime.datatype,
  354.        moviesetter.datatype,
  355.        film.datatype,
  356.        directory.datatype,
  357.        markabletextdtclass
  358.  
  359. gifanim.datatype/--input_format--           gifanim.datatype/--input_format--
  360.  
  361.     NAME
  362.         GIF ANIM -- GIF Animation format
  363.  
  364.     DESCRIPTION
  365.         <Not written yet, sorry>
  366.  
  367.     SEE ALSO
  368.         gif.doc, gif89a.doc, compress.gif
  369.  
  370. gifanim.datatype/ADTM_LOADFRAME               gifanim.datatype/ADTM_LOADFRAME
  371.  
  372.     NAME
  373.         ADTM_LOADFRAME -- Load frame
  374.  
  375.     FUNCTION
  376.         The ADTM_LOADFRAME method is used to obtain the bitmap and timing
  377.         data of the animation.
  378.         The given timestamp will be used to find a matching timestamp
  379.         in the internal FrameNode list. If it was found, the corresponding
  380.         timing, bitmap and colormap data are stored into the struct
  381.         adtFrame. If the bitmap wasn't loaded, this method attempts to
  382.         load it from disk.
  383.  
  384.     RESULT
  385.         the bitmap ptr if a bitmap was found,
  386.         0 (and result2 with the reason).
  387.  
  388. gifanim.datatype/ADTM_UNLOADFRAME           gifanim.datatype/ADTM_UNLOADFRAME
  389.  
  390.     NAME
  391.         ADTM_UNLOADFRAME -- Unload frame contents
  392.  
  393.     FUNCTION
  394.         The ADTM_UNLOADFRAME method is used to release the contents of a
  395.         animation frame.
  396.  
  397.         This method frees the bitmap data found in adtFrame.
  398.  
  399.     RESULT
  400.         Returns always 0UL.
  401.  
  402. gifanim.datatype/DTM_WRITE                         gifanim.datatype/DTM_WRITE
  403.  
  404.     NAME
  405.         DTM_WRITE -- Save data
  406.  
  407.     FUNCTION
  408.         This method saves the object's contents to disk.
  409.  
  410.         If dtw_Mode is DTWM_IFF, the method is passed unchanged to the
  411.         superclass, animation.datatype, which writes a single IFF ILBM
  412.         picture.
  413.  
  414.         If dtw_mode is DTWM_RAW, the object saved an GIF Animation stream 
  415.         to the filehandle given, starting with the current frame until
  416.         the end is reached.
  417.         The sequence saved can be controlled by the ADTA_Frame, ADTA_Frames
  418.         and ADTA_FrameIncrement attributes (see TAGS section below).
  419.  
  420.     TAGS
  421.         When writing the local ("raw") format, GIF Animation, the following
  422.         attributes are recognized:
  423.  
  424.         ADTA_Frame (ULONG) - start frame, saving starts here.
  425.             Defaults to the current frame displayed.
  426.  
  427.         ADTA_Frames (ULONG) - the number of frames to be saved,
  428.             Defaults to (max_num_of_frames - curr_frame).
  429.  
  430.         ADTA_FrameIncrement (ULONG) - frame increment when saving.
  431.             Defaults to 1, which means: "jump to next frame".
  432.  
  433.     NOTE
  434.         - Any sound attached to the animation will NOT be saved.
  435.  
  436.         - A CTRL-D signal to the writing process aborts the save.
  437.  
  438.     RESULT
  439.         Returns 0 for failure (IoErr() returns result2), non-zero
  440.         for success.
  441.  
  442. gifanim.datatype/MAIN                                   gifanim.datatype/MAIN
  443.  
  444.     INTRODUCTION
  445.         Datatypes class for GIF animations. Based on "giftopnm" by David
  446.         Koblas, "ppmtogif" by Marcel Wijkstra <wijkstra@fwi.uva.nl> and
  447.         David Rowley <mgardi@watdscu.waterloo.edu> and the CBM datatypes 
  448.         example source/ documents written by David Junod.
  449.  
  450.     LEGAL
  451.       * Note that this implementation uses LZW, which is PATENTED by UniSys
  452.         in the U.S.A.
  453.  
  454.         Therefore, this application must not be used inside the United
  455.         States of America except for research purposes.
  456.  
  457.       - Compuserves banner:
  458.  
  459.       "The Graphics Interchange Format(c) is the Copyright property of
  460.       CompuServe Incorporated. GIF(sm) is a Service Mark property of
  461.       CompuServe Incorporated."
  462.  
  463.       - "giftopnm" legal info:
  464.       +-------------------------------------------------------------------+
  465.       | Copyright 1990, 1991, 1993, David Koblas.  (koblas@netcom.com)    |
  466.       |   Permission to use, copy, modify, and distribute this software   |
  467.       |   and its documentation for any purpose and without fee is hereby |
  468.       |   granted, provided that the above copyright notice appear in all |
  469.       |   copies and that both that copyright notice and this permission  |
  470.       |   notice appear in supporting documentation.  This software is    |
  471.       |   provided "as is" without express or implied warranty.           |
  472.       +-------------------------------------------------------------------+
  473.  
  474.     REQUIREMENTS
  475.         - You need at least Kick/WB 3.0.
  476.           | Many people wrote me that they cannot find an
  477.           | "animation.datatype" class.
  478.           | Only the 3.1 release contains it. (Subclasses of)
  479.           | animation.datatype can run under 3.0.
  480.  
  481.         - "datatypes/animation.datatype", >= V41
  482.           "animation.datatype V41" requires itself some
  483.           libraries/boopsi classes:
  484.         - "realtime.library", >= V39              - for timing
  485.         - "gadgets/tapedeck.gadget" (any version) - for the controls
  486.  
  487.            If you want to attach samples, you need "sound.datatype" >= V39
  488.            and your prefereed subclass (8svx.datatype for IFF 8SVX samples
  489.            etc.).
  490.  
  491.     USAGE
  492.         If the datatypes descriptor file was activated, any attempt to load
  493.         a GIF anim stream using GMultiView, MultiView, AmigaGuide or
  494.         SwitchWindow will load and play the animation. If the source was a
  495.         file, gifanim.datatype loads frames dynamically from disk.
  496.  
  497.         If you want to save the current animation in gifanim.datatype's
  498.         local format, use MultiView's "Project/Save As..." menu (or
  499.         GMultiView's "Project/Save As Raw...").
  500.         gifanim.datatype saves the current animation, starting with the
  501.         current frame as GIF animation.
  502.  
  503.         If you want to attach samples to the animation, you must edit the
  504.         prefs file (ENV:Classes/DataTypes/gifanim.prefs) and add the
  505.         following line:
  506.         VERBOSE SAMPLE="ram:have_a_nice_day.8svx"
  507.         Which loads and attaches the sample "ram:have_a_nice_day.8svx" to
  508.         the animation. See gifanim.datatype.doc/preferences for a complete
  509.         description of the prefs file.
  510.  
  511.     INSTALLATION
  512.         After unpacking this archive:
  513.         Because this version does not include an Installer script, you have
  514.         to do the installation manually through the shell:
  515.  
  516.           - Unpack this archive and copy the "gifanim.datatype" to
  517.             SYS:Classes/DataTypes/:
  518.  
  519.         Copy CLONE FROM "gifanim.datatype" TO
  520.          "SYS:Classes/DataTypes/gifanim.datatype"
  521.  
  522.           - Then copy the datatypes descriptor into the DEVS:DataTypes
  523.             directory.
  524.             If the descriptor already exists, you should not replace it,
  525.             otherwise you may loose "toolnodes" and other settings stored in
  526.             the existing descriptor.
  527.  
  528.      Copy CLONE FROM "GIFANIM(%|.info)" TO DEVS:Datatypes/
  529.  
  530.     SOURCE
  531.         Source is included as an example how to write an
  532.         animation.datatype subclass which deals with things chunky bitmaps
  533.         deltas and an encoder...
  534.  
  535.     AUTHOR
  536.         If you want to blame me, report any bugs, or wants a new version
  537.         send your letter to:
  538.                         Roland Mainz
  539.                         Hohenstaufenstraße 8
  540.                         52388 Nörvenich
  541.                         GERMANY
  542.  
  543.         Phone: (+49)(0)2426/901568
  544.         Fax:   (+49)(0)2426/901569
  545.  
  546.         EMAIL is also available (if you want to send me attachments
  547.         larger than 1MB (up to 5MB, more with my permission):
  548.  
  549.         GISBURN@w-specht.rhein-ruhr.de
  550.  
  551.         Up to May 1998 I'm reachable using this email address, too:
  552.         Reinhold.A.Mainz@KBV.DE
  553.  
  554.         | Please put your name and address in your mails !
  555.         | German mailers should add their phone numbers.
  556.         | See BUGS section above when submitting bug reports.
  557.  
  558.         Sorry, but I can only look once a week for mails.
  559.         If you don't hear something from me within three weeks, please
  560.         send your mail again (but watch about new releases) (problems with
  561.         this email port are caused by reconfigurations, hackers, network
  562.         problems etc.).
  563.  
  564.         The  entire  "gifanim.datatype"  package  may  be  noncommercially
  565.         redistributed, provided  that  the package  is always  distributed
  566.         in it's complete  form (including it's documentation). A small
  567.         copy fee  for media costs is okay but any kind of commercial
  568.         distribution is strictly forbidden without my permission !
  569.         Comments and suggestions how to improve this program are
  570.         generally appreciated!
  571.  
  572.         Thanks to David Junod, who wrote the animation.datatype and lots of
  573.         the datatypes example code, David Koblas for his "giftopnm"
  574.         and other people for their compression formats, Peter McGavin for
  575.         his C2P function, Matt Dillon for his DICE, Olaf 'Olsen' Barthel
  576.         for his help, ideas and some text clips from his documentations.
  577.  
  578. gifanim.datatype/OM_DISPOSE                       gifanim.datatype/OM_DISPOSE
  579.  
  580.     NAME
  581.         OM_DISPOSE -- Delete a gifanim.datatype object.
  582.  
  583.     FUNCTION
  584.         The OM_DISPOSE method is used to delete an instance of the
  585.         gifanim.datatype class. This method is passed to the superclass when
  586.         it has completed.
  587.         This method frees all frame nodes and their contents (bitmaps,
  588.         colormaps, samples etc.)
  589.  
  590.     RESULT
  591.         The object is deleted. 0UL is returned.
  592.  
  593. gifanim.datatype/OM_NEW                               gifanim.datatype/OM_NEW
  594.  
  595.     NAME
  596.         OM_NEW -- Create a gifanim.datatype object.
  597.  
  598.     FUNCTION
  599.         The OM_NEW method is used to create an instance of the
  600.         gifanim.datatype class.  This method is passed to the superclass
  601.         first. After this, gifanim.datatype parses the prefs file and makes
  602.         a scan through the data to get index information. Frame bitmaps are
  603.         loaded if the input stream isn't seekable, colormaps and the first
  604.         frame are loaded immediately.
  605.         If a sample was set in the prefs, it will be loaded and attached
  606.         to the animation.
  607.  
  608.     ATTRIBUTES
  609.         The following attributes can be specified at creation time.
  610.  
  611.         DTA_SourceType (ULONG) -- Determinates the type of DTA_Handle
  612.             attribute. Only DTST_FILE and DTST_RAM are supported.
  613.             If any other type was set in a given DTA_SourceType,
  614.             OM_NEW will be rejected.
  615.             Defaults to DTST_FILE.
  616.  
  617.         DTA_Handle -- For DTST_FILE, a BPTR filehandle is expected. This
  618.             handle will be created by datatypesclass depeding on the DTF_#?
  619.             flag, which is DTF_BINARY here.  DTST_FILE, datatypesclass
  620.             creates a file handle from the given DTA_Name and DTA_Handle
  621.             (a BPTR returned by Lock).
  622.             A DTST_RAM (create empty object) source type requires a NULL
  623.             handle.
  624.  
  625.     RESULT
  626.         If the object was created a pointer to the object is returned,
  627.         otherwise NULL is returned.
  628.  
  629. gifanim.datatype/preferences                     gifanim.datatype/preferences
  630.  
  631.    NAME
  632.        preferences
  633.  
  634.    DESCRIPTION
  635.        The "ENV:Classes/DataTypes/gifanim.prefs" file contains global
  636.        settings for the datatype.
  637.        The preferences file is an ASCII file containing one line where the
  638.        preferences can be set.
  639.        It can be superset by a local variable with the same name.
  640.  
  641.        Each line can contain settings, special settings for some projects
  642.        can be set using the MATCHPROJECT option.
  643.        Lines beginning with a '#' or ';' chars are treated as comments.
  644.        Lines are limitted to 256 chars.
  645.  
  646.    TEMPLATE
  647.        MATCHPROJECT/K,VERBOSE/S,STRICTSYNTAX/S,NOSTRICTSYNTAX/S, 
  648.        MODEID/K/N,16BITCHUNKY=24BITCHUNKY=TRUECOLOR/S,
  649.        NO16BITCHUNKY=NO24BITCHUNKY=NOTRUECOLOR/S,FPS/K/N,
  650.        SAMPLE/K,SAMPLESPERFRAME=SPF/K/N,VOLUME/K/N,LOADALL/S,
  651.        NOLOADALL/S,ENC_INTERLACE/S,ENC_NO_INTERLACE/S,
  652.        ENC_BACKGROUNDPEN=ENC_BG/K/N,ENC_TRANSPARENTPEN=ENC_TRANSPARENT/K/N
  653.  
  654.        MATCHPROJECT -- The settings in this line belongs only to this
  655.            project(s), e.g. if the case-insensitive pattern does not match,
  656.            this line is ignored.
  657.            The maximum length of the pattern is 128 chars.
  658.            Defaults to #?, which matches any project.
  659.  
  660.        VERBOSE -- Print information about the animation. Currently
  661.           the frame numbers and the used compression are printed, after all
  662.           number of scanned/loaded frames, set FPS rate, dimensions (width/
  663.           height/depth), sample information etc.
  664.  
  665.        STRICTSYNTAX -- Prompt syntax errors in the gif streams.
  666.  
  667.        NOSTRICTSYNTAX -- Turns STRICTSYNTAX off
  668.  
  669.        MODEID -- Select screen mode id of datatype (will be stored in
  670.            ADTA_ModeID). Note that the DOS ReadArgs function used for parsing
  671.            fetches a SIGNED long. The bit 31 will be represented by minus
  672.            '-'. (example: "MODEID=266240" sets the mode to the A2024 screen
  673.            mode id)
  674.            Defaults to -1, which means: Use the best screenmode available for
  675.            the given width, height and depth.
  676.  
  677.        16BITCHUNKY
  678.        24BITCHUNKY
  679.        TRUECOLOR -- Create 24 bit chunky bitmaps, if possible.
  680.            Note that the 16BITCHUNKY and the 24BITCHUNKY options will be
  681.            seperated in the future. The TRUECOLOR option selects the
  682.            best truecolor depth in this case...
  683.  
  684.        NO16BITCHUNKY
  685.        NO24BITCHUNKY
  686.        NOTRUECOLOR -- Turns 24BITCHUNKY option off. (Default)
  687.            Note that the 16BITCHUNKY and the 24BITCHUNKY options will be
  688.            seperated in the future. The TRUECOLOR option selects the
  689.            best truecolor depth in this case...
  690.  
  691.        FPS -- Frames Per Second
  692.            A value of 0 here means: Use default FPS.
  693.  
  694.        SAMPLE -- Attach the given sample to the animation. The sample will
  695.            be loaded using datatypes (GID_SOUND).
  696.            Only one sample can be attached to one animation stream, any
  697.            following attempt to attach a sample will be ignored.
  698.  
  699.        SAMPLESPERFRAME -- Set samples per frame rate for sound. This
  700.            overrides the own internal calculations to get rid of rounding
  701.            errors.
  702.  
  703.        VOLUME -- Volume of the sound when playing.
  704.            Defaults to 64, which is the maximum. A value greater than 64 will
  705.            be set to 64.
  706.  
  707.        LOADALL -- Load all frames into memory.
  708.  
  709.        NOLOADALL -- Turns off the LOADALL flag, which may be set in a prefs-
  710.            line before. This switch is set per default, and can be turned off
  711.            by the LOADALL option, later it can be turned on again by this
  712.            option.
  713.  
  714.        Encoder related options:
  715.        ENC_INTERLACE    - create interlaced gif animation
  716.  
  717.        ENC_NO_INTERLACE - create non-interlaced gif animation 
  718.            (set per default).
  719.  
  720.        ENC_BACKGROUNDPEN
  721.        ENC_BG           - background pen number
  722.            Defaults to 0 (e.g. default bg pen)
  723.  
  724.        ENC_TRANSPARENTPEN
  725.        ENC_TRANSPARENT - transparent pen number
  726.            Defaults to -1 (means: no transparent pen).
  727.  
  728.  
  729.    NOTE
  730.        - An invalid prefs file line will be ignored and forces the VERBOSE
  731.          output.
  732.  
  733.    BUGS
  734.        - Low memory may cause that the prefs file won't be parsed.
  735.  
  736.        - Lines are limitted to 256 chars
  737.  
  738.        - An invalid prefs file line will be ignored.
  739.  
  740.        - The sample path length is limitted to 200 chars. A larger
  741.          value may crash the machine if an error occurs.
  742.  
  743.